Weapons

This lesson is all about weapons. We'll start with a simple system of one turret, one barrel, and one flare. More complex ideas such as alternating fire points, restore animations and disable-able weapons will be covered in Lesson4. For now, let's begin by opening example3.bos into Scriptor.


Signal & Set-Signal-Mask

Signals are vital to accurate aiming of a weapon amongst other things. They consist of a few parts, firstly the "#define SIG_AIM 2" defines the signal with name SIG_AIM has the value of 2. This is important as each signal must have a separate value so they are not confused by the system. The numbers must also be a value of 2^x, so first is 2, then 4, 8 and 16. Rarely will you get near or above 4 signals. You can use any name for a signal, providing you haven't used that word as a variable elsewhere, but as a standard, people sually stick to the SIG_AIM1, SIG_MOV, etc. convention.

The signal is the script's way to instantly abort a certain action by the command. A signal is established by the command "Set-Signal-Mask SIG_AIM;" and aborted by "Signal SIG_AIM;". Let us examine how it works in this case. As soon as an enemy, targetable enemy comes into the range of this unit's primary weapon, a kill-signal is sent to abort all eventual previous aiming and the unit commences the aiming animation, trying to target (more about that in a bit). Direcly after that, a new signal is set to run, so basically, the signal is used to constantly update the script with the exact coordinations of the enemy unit.

When you select the unit and force it to target a specific enemy, another kill-signal is sent to instantly abort any eventual aiming for other units and start to target the enemy of your choice. Same thing happens if the targetted enemy is destroyed by another unit.

The "return(TRUE);" part is sent when the aiming is completed and the unit should fire.


AimPrimary(heading, pitch)

So now we get to the interesting part, the actual, seen animation of the unit in the game. This instance will turn the weapon barrels until they point directly at it's target. The TA script automatically calculates the heading and the pitch (altitude) of the enemy unit and sends them down to the animation strings that tune in to these values.

AimFromPrimary(piecenum)

This is a relatively simple function. Again the TA engine is requesting a model object/piece. In this case it's the one we'll be aiming from, and this is usually the turret which it will be used to aim...that is hoping you've set up your model object origin points corrects.

Later with two or more turrets using only one weapon, you may decide to aim from a point in-between them, or to alternate between each turret as the aim point. How to do this will be rather obvious once we've covered the logic of alternating firepoints.

QueryPrimary(piecenum)

Apart from the cool animation, this is the actual piece that shoots the weapon, be it a projectile / missile / plasma emission.

FirePrimary()

This is called as the weapon is fired, and contains the actual firing animation. This is the part where you tell the script what you want your unit to do when it fires. In this case, it shows up a flare (which is the simulation of a muzzleflash), throws back the cannon, hides the flare and starts slowly moving back.

Feuer frei!

Also, a few quirks about TA. The second and third weapons have Primary replaced with Secondary and Tertiary respectively. Any stockpile-able weapon (as for example a nuke) must be the primary weapon, thus you cannot have two or more of such per unit. Also, any requiring direct player command to fire via the D-gun button need to be the Tertiary weapon (weapon3 in the .fbi). Command weapons which are not linked to the D-gun button can be any weapon, but you'd better tell the players they'll need to click for each target.